home *** CD-ROM | disk | FTP | other *** search
/ Precision Software Appli…tions Silver Collection 4 / Precision Software Applications Silver Collection Volume 4 (1993).iso / stats / eval108.exe / EVAL.DOC < prev    next >
Text File  |  1992-07-17  |  14KB  |  374 lines
  1.  
  2.  
  3.  
  4.      EVAL V1.08 Copyright (c) 1991-1992 Copy Con Incorporated        Page 1
  5.  
  6.  
  7.      TO PRINT THIS FILE, TYPE "COPY EVAL.DOC PRN" AT THE DOS PROMPT.
  8.  
  9.  
  10.      OVERVIEW
  11.      --------
  12.      EVAL is a mathematical expression evaluator, capable of evaluating
  13.      virtually any formula, including those with trigonometric functions,
  14.      complex numbers, and user-defined variables. Formulas are typed in at
  15.      the command line, and the formula and outcome (and optionally the
  16.      variable values) are immediately displayed on your screen, or can be
  17.      sent to any device or file via standard DOS redirection.
  18.  
  19.  
  20.      DISCLAIMER
  21.      ----------
  22.      EVAL is distributed on an "AS IS" basis without warranty, expressed or
  23.      implied. Considerable testing effort has been expended, but the user
  24.      is advised to check the program's suitability before relying on it.
  25.      The user assumes full risk as to the results of using this program.
  26.      Any liability of the author will be limited exclusively to product
  27.      replacement. In no event shall the author be liable for any incidental
  28.      or consequential damages arising from the use, or inability to use
  29.      this program.
  30.  
  31.  
  32.      REGISTRATION
  33.      ------------
  34.      The unregistered version of EVAL is freely distributable and fully
  35.      functional, and may be used for a 30-day trial period. If you plan to
  36.      continue using EVAL after the trial period, you are obligated to pay
  37.      the modest registration fee of $20. Registered users will receive the
  38.      latest version of EVAL with the "nag" messages removed, along with a
  39.      smaller, math-chip version of EVAL. Registration also entitles you to
  40.      one free upgrade upon request, and half-priced subsequent upgrades.
  41.  
  42.      All registration information is contained in the REGISTER.TXT file. If
  43.      that file is missing, register by sending a check or money order for
  44.      $20 in U.S. dollars, drawn on a U.S. bank, to:
  45.  
  46.         Copy Con Incorporated
  47.         PO Box 23255
  48.         Baltimore MD 21203-5255
  49.  
  50.      Please specify 3.5" or 5.25" diskette. MD residents add 5% sales tax.
  51.      We thank you for your support.
  52.  
  53.  
  54.  
  55.      EVAL V1.08 Copyright (c) 1991-1992 Copy Con Incorporated        Page 2
  56.  
  57.  
  58.      OPERATION
  59.      ---------
  60.      EVAL is activated from the command line, using the format
  61.  
  62.         EVAL [[~]variable=expression;...] expression [options]
  63.  
  64.      Expressions are mathematical formulas built with the supported
  65.      functions, operators, constants and variables.
  66.  
  67.  
  68.      FUNCTIONS
  69.      ---------
  70.      Following are the functions that EVAL supports:
  71.  
  72.         Function  Description
  73.         --------  -----------
  74.           abs     Absolute value
  75.           acos    Arc cosine
  76.           arg     Angle of input value in the complex plane
  77.           asin    Arc sine
  78.           atan    Arc tangent
  79.           ceil    Smallest integer not less than input value (rounds up)
  80.           conj    Complex conjugate of input value
  81.           cos     Cosine
  82.           cosh    Hyperbolic cosine
  83.           csc     Cosecant
  84.           ctn     Cotangent
  85.           cub     Cube root
  86.           exp     E to the power of input value
  87.           flr     Largest integer not more than input value (rounds down)
  88.           frac    Fractional part of input value
  89.           imag    Imaginary part of complex number
  90.           int     Integer part of input value
  91.           ln      Natural logarithm
  92.           log     Natural logarithm (same as LN)
  93.           logt    Base 10 logarithm
  94.           norm    Square of the absolute value
  95.           rand    Random integer between 1 and input value (max 32767)
  96.           real    Real part of complex number
  97.           sec     Secant
  98.           sgn     Sign of input value (positive=1, negative=-1, zero=0)
  99.           sin     Sine
  100.           sinh    Hyperbolic sine
  101.           sqr     Square (x^2)
  102.           sqrt    Square root
  103.           tan     Tangent
  104.           tanh    Hyperbolic tangent
  105.  
  106.  
  107.  
  108.      EVAL V1.08 Copyright (c) 1991-1992 Copy Con Incorporated        Page 3
  109.  
  110.  
  111.      FUNCTIONS (continued)
  112.      ---------------------
  113.      Parentheses are optional when using functions; if they are not used,
  114.      only the first value following the function will be considered the
  115.      argument. For example:
  116.  
  117.         sin pi      evaluates to   sin(pi)
  118.         sin pi/2    evaluates to   sin(pi)/2
  119.         sin(pi/2)   evaluates to   sin(pi/2)
  120.  
  121.      Use of functions without parentheses is potentially erroneous, and it
  122.      is generally preferable to use parens to indicate function arguments.
  123.  
  124.  
  125.      OPERATORS
  126.      ---------
  127.      Each operator has a precedence, and operators with higher precedence
  128.      are evaluated before operators with lower precedence. Operators with
  129.      equal precedence are handled from left to right within a function.
  130.  
  131.      Precedence is indicated by order in the following table (the first
  132.      line has the highest precedence):
  133.  
  134.         Operators  Description
  135.         ---------  -----------
  136.            ( )     Left parenthesis,Right parenthesis
  137.             !      Unary factorial
  138.            + -     Unary sign
  139.             ^      Exponential
  140.           * / %    Multiplication,Division,Modulus
  141.            + -     Addition,Subtraction
  142.  
  143.      Where it is not ambiguous, multiplication can be indicated by
  144.      adjacency: 8(6-4) = 8*(6-4) = 16. Implicit multiplication is
  145.      potentially erroneous, and it is generally preferable to use the '*'
  146.      symbol to indicate multiplication.
  147.  
  148.  
  149.      CONSTANTS
  150.      ---------
  151.      EVAL supports numeric constants, and three alphabetic constants, PI,
  152.      E, and I. Alphabetic constants cannot directly follow functions; use
  153.      "cos pi" or "cos(pi)", not "cospi". Numeric constants need not be
  154.      separated from functions; "sin3" is okay.
  155.  
  156.      Numerical constants are entered just as you would ordinarily write
  157.      them. They can be preceeded with optional + or - signs. The following
  158.      are all valid numerical entries:
  159.  
  160.                         6.78    0.678   .678   -678
  161.  
  162.      Blanks are not permitted in numbers; the expression "7 8" would be
  163.      evaluated as 7 times 8, not 78.
  164.  
  165.  
  166.  
  167.      EVAL V1.08 Copyright (c) 1991-1992 Copy Con Incorporated        Page 4
  168.  
  169.  
  170.      CONSTANTS (continued)
  171.      ---------------------
  172.      Complex numbers can be used as easily as real numbers. Any of EVAL's
  173.      functions which are mathematically defined for complex values (like
  174.      SIN and EXP) will accept complex arguments. Complex numbers are
  175.      entered using the form "x+yi" where "i" is equivalent to the square
  176.      root of -1. The following are all valid complex number entries:
  177.  
  178.                          3+4i    5.2-3.45i    -63i
  179.  
  180.      Alphabetic constants can also be used as easily as real numbers; just
  181.      be careful not to string them together with functions, variables, and
  182.      other alphabetic constants; instead of "lne+api", use "ln e + a pi",
  183.      or "ln(e)+a*pi". "3pi/2" and "4i" are valid, as EVAL can tell where
  184.      one constant ends and another begins.
  185.  
  186.      Following are the approximate values of the alphabetic constants:
  187.  
  188.         PI = 3.14159265
  189.         E  = 2.71828183
  190.         I  = sqrt(-1)
  191.  
  192.  
  193.      VARIABLES
  194.      ---------
  195.      The letters A-Z (except for E and I) are set aside as user-definable
  196.      variables. Variables have a default value of 0, and are assigned
  197.      values using the equals sign. For example:
  198.  
  199.         EVAL a=pi;b=cub(8);b*cos(a)
  200.  
  201.      will assign a value of PI to A, a value of 2 to B, and will print out
  202.      the value of B times the cosine of A. As with alphabetic constants,
  203.      variables cannot directly follow functions; use a space delimiter, or
  204.      parentheses as above.
  205.  
  206.  
  207.      OPTIONS
  208.      -------
  209.      Options must be in the form "OPTION:value", as in "a:g" or "d:5". Case
  210.      is not important. Separate options with spaces.
  211.  
  212.      Option  Description
  213.      ------  -----------
  214.        A     Angular unit - whether angles will be expressed as degrees,
  215.              radians, or grads. Use the first letter of the unit, as in
  216.              "a:d". By default, angular units are expressed as radians.
  217.  
  218.        D     Significant digits - the number of significant digits shown in
  219.              the expression outcome. Range is 1 thru 18; the default is 10.
  220.  
  221.  
  222.  
  223.      EVAL V1.08 Copyright (c) 1991-1992 Copy Con Incorporated        Page 5
  224.  
  225.  
  226.      OPTIONS (continued)
  227.      -------------------
  228.  
  229.      Option  Description
  230.      ------  -----------
  231.       R[P]   Recursions - number of times the formula will repeat itself,
  232.              starting at the tilde (~) character. For example,
  233.  
  234.                 EVAL a=0 ; ~a=a+1 ; a v:n r:20
  235.  
  236.              will parse the entire formula, then repeat from the tilde
  237.              character a total of twenty times. If the 'rp:' option is
  238.              used instead, EVAL will wait after each screen for a keypress.
  239.              Range is 0 thru 2147483646. Default is 0.
  240.  
  241.        V     Show variables - whether variables and their values will be
  242.              displayed as they are assigned values. If this option is set
  243.              to F, the formulas will also be shown. Default is Y.
  244.  
  245.  
  246.      ERROR MESSAGES
  247.      --------------
  248.      Following are error messages you may come across, along with their
  249.      descriptions and corresponding DOS errorlevels:
  250.  
  251.      Level  Message & Description
  252.      -----  ---------------------
  253.        1    Invalid input - you have attempted to use an unsupported
  254.             option, or you have exceeded an option's range.
  255.  
  256.        2    Invalid function '(function)' - you have attempted to use an
  257.             unsupported function. If it's a common function, let us know,
  258.             and we will add it.
  259.  
  260.        3    Ctrl-Break pressed - self-explanatory. No message is shown.
  261.  
  262.        4    Expression too complex - your formula has 128 or more
  263.             constants, or more than 255 combined constants, functions, and
  264.             operators.
  265.  
  266.        5    Invalid operator '(op)' - you have attempted to use an
  267.             unsupported operator. If it's a common operator, let us know,
  268.             and we will add it.
  269.  
  270.        6    Mixmatched parentheses - there were an uneven amount of
  271.             parentheses, or a right parenthesis was encountered before its
  272.             matching left paren.
  273.  
  274.        7    Invalid use of functions - functions cannot be directly
  275.             followed by an operator (unless the operator is a "+" or "-"
  276.             indicating the sign of the value that follows).
  277.  
  278.  
  279.  
  280.      EVAL V1.08 Copyright (c) 1991-1992 Copy Con Incorporated        Page 6
  281.  
  282.  
  283.      ERROR MESSAGES (continued)
  284.      --------------------------
  285.  
  286.      Level  Message & Description
  287.      -----  ---------------------
  288.        8    Invalid use of operators - operators cannot be directly
  289.             followed by other operators (unless the second operator is a
  290.             "+" or "-" indicating the sign of the value that follows).
  291.  
  292.        9    Invalid variable '(variable)' - an attempt was made to assign a
  293.             value to a constant or a non-variable.
  294.  
  295.       10    Division by zero - a denominator in your formula has a value of
  296.             zero, which is mathematically undefined.
  297.  
  298.       11    Argument domain/range - a function in the formula cannot
  299.             evaluate its input value, as the value is outside of the
  300.             function's range.
  301.  
  302.       12    Argument singularity - formula would result in a singularity.
  303.  
  304.       13    Overflow - the formula evaluates to a result greater than the
  305.             maximum allowed.
  306.  
  307.       14    Underflow - the formula evaluates to a result less than the
  308.             minimum allowed.
  309.  
  310.       15    Total significance loss - formula would produce a result with
  311.             a total loss of significant digits.
  312.  
  313.  
  314.      EXAMPLES
  315.      --------
  316.      EVAL sqrt3 d:4
  317.           displays the square root of 3, limited to 4 significant digits.
  318.           ( sqrt3 evaluates to sqrt(3) )
  319.  
  320.      EVAL a=pi ; b=cub 8 ; b*cos(a)
  321.           assigns a value of PI to A, a value of 2 to B, and displays the
  322.           value of B times the cosine of A. The values of A and B are also
  323.           displayed. (The spaces around the semicolons are not required)
  324.  
  325.      EVAL x=1/10;asin(5x) a:d v:n
  326.           assigns a value of .1 to X, and displays the arcsine of quantity
  327.           5 times X, expressed in degrees. The value of X is not displayed.
  328.           ( 5x is equivalent to 5*x )
  329.  
  330.      EVAL (2+4i)/(6-8i)
  331.           displays the result of the first complex number divided by the
  332.           second complex number.
  333.  
  334.  
  335.  
  336.      EVAL V1.08 Copyright (c) 1991-1992 Copy Con Incorporated        Page 7
  337.  
  338.  
  339.      EXAMPLES (continued)
  340.      --------------------
  341.      EVAL 3*4!
  342.           displays the result of 4 factorial, times 3. Since factorials are
  343.           higher in precedence than multiplication, use "EVAL (3*4)!" to
  344.           show 3 times 4 quantity, factorial.
  345.  
  346.      EVAL z=2+3i ; ~z=log z ; z  v:n d:18 rp:120
  347.           sets z equal to complex number 2+3i, sets z to the logarithm of
  348.           its current value, displays the new value to 18 significant
  349.           digits, then repeats from the logarithm step 120 times, pausing
  350.           after each screen.
  351.  
  352.      EVAL a=1 ; ~b=b+1/a ; a=a+2 ; b=b-1/a ; a=a+2 ; 4b  v:n d:18 r:6000
  353.           assigns 1 to a, adds 1/a to b, adds 2 to a, subtracts 1/a from b,
  354.           adds 2 more to a, prints 4*b to 18 significant digits, then
  355.           repeats the formula from the ~ symbol 6000 times. Incidentally,
  356.           this is a popular method of calculating the value of PI. (Well,
  357.           yeah, I suppose you could just use EVAL PI, if you're in a hurry
  358.           or something.... :^)
  359.  
  360.  
  361.      CORRESPONDENCE
  362.      --------------
  363.      If you have questions, comments, suggestions, bug reports, et cetera,
  364.      feel free to contact us by one of the following methods:
  365.  
  366.      1: By modem at The Programmer's Corner (301-596-7692 or 410-995-6873).
  367.         Send a message to user number 3000, and check back in a couple of
  368.         work days for a reply.
  369.  
  370.      2: By U.S. Mail at the address given on the first page. If you would
  371.         like a reply, please include a self-addressed, stamped envelope.
  372.  
  373.      We look forward to hearing from you.
  374.